Q66T ACW = JURUOJUT B]9R19 


23 


Powering Up 


Oracle Power Objects 


Really Powerful Classes 


Reusing OPO Classes to Provide Linked Information 


By Rick Greenwald 





ho was it that said “Give me a lever long enough, and a place to stand, and | 
can move the world?” What | say is “Give me a set of powerful flexible class- 


es, and | will actually deliver the project on time.” With the Knowledge you gain in 
this month’s article, you'll be able to make good on this equally impressive boast. 


The power of an object class derives from 
your ability to create instances of the object 
class that automatically inherit all the 
encapsulated functionality of the class. The 
more often you use instances of an object 
class, the greater the accumulated produc- 
tivity that is delivered by the object class. 
This month, using the knowledge from our 
last three articles — and some new features 
in the 1.0.16 maintenance release of Oracle 
Power Objects (OPO) — we'll learn to cre- 


ate truly powerful object classes. 


A Self-Documenting Bound 

Data Field Class 

To create an object class that can be widely 
used, we should try to determine some 
type of functionality that is commonly 
needed in a variety of OPO applications. 


One of the ways that OPO helps devel- 
opers is by allowing them to easily bind 
text fields to columns in a database. This 
makes OPO a great tool for creating 
applications that permit users to interact 
with the data in a database. Although 
most users will be happy to use your 
applications without knowing about the 
database columns that are bound to data 
field objects, some of your users may 
want the ability to understand the link- 
age between a data field and a database 
column. You may also need to rapidly 
find out the column associated with a 
data field in your debugging process. You 
can create a class that automatically 
shows the bound column for any partic- 
ular field by responding to a key stroke. 


The OnKey Method 
To create the object class, you need a 
method that was just added to OPO data 
fields in the 1.0.16 maintenance release. 
The OnKey method for a data field is 
fired whenever a user enters a key stroke 
within the boundaries of the particular 
field. The OnKey method automatically 
passes three parameters: 
m keychar is a representation of the single 
character for the key that was pressed; 
m keycode provides a code that indicates 
which key was pressed if it is a non- 
ASCI key (e.g. a function key); and 
m shift indicates if the key was pressed in 
conjunction with (Shift). 


(For complete information on the OnKey 
method, please refer to the documentation 
for the maintenance release.) 


We want to create functionality in our 
object class that will allow a user to press 
on any data field and cause a message 
box to appear with the name of the associ- 
ated database column. 


Creating the Class 
Let’s move right to creating our object class. 


Step 1: Create a library to hold your class 
by clicking on the New Library button on 
the toolbar or by selecting File | New 
Library. Set the Name property of the 
library to General. 


Step 2: Create a class in the application by 
clicking on the New Class button or by 
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selecting File | New Class. Size the class so that it’s about 
Y2" high and about 2" wide. Set the Name property of 
the class to clsBoundDataField, its HasBorder property 
to False, and the Transparent property to True. 


You'll want the class to be wide enough so that you can add a 
fairly long data field without having to resize the class. By set- 
ting the HasBorder and ‘Transparent properties of the class, 
you ensure that you can add an instance of the class to any 
form without interfering with the form’s overall appearance. 


Step 3: Add a data field to the class and then size the data 
field so that a 1/8" space is between the edge of the data field 
and the border of the class container. Set the Name property 
of the data field to fldBoundDataField (see Figure 1). 











SH] racle Power Objects sd 


File Edit Object View Run Window Help 


[= eisBoundDataFietd Proper 
Fle) Cells 


| oBitmap | | 
| ¢BitmapTiled [False |_| 
& ChildClick 
& ChildDbIClick 
& ChildOnKey 
& ChildPostChange 
| ecolorFil ss (| 
| ©DefaultCondition |_| 
& DeleteRow 
& GoNsdtLine 
& GoNxtPaqge 


[=| Class - clsBoundDataField [~ [|| 
__ TART eee 


fldBoundDataField | 
| 


© GoPrvLine 
© GoPrnPage 


Main GENERAL 


Deletes a row 


Figure 1: The clsBoundDataField class. 


You want to leave a small border between the data field 
and the edge of the class so that an instance of the class 
will not accidentally “contain” other objects in your appli- 
cation. Also, leaving a small border allows you to “grab” 
the corners of the class or data field with the mouse and 
then easily resize each object. The values for the Datatype 
and DataSource properties of the data field are not very 
important since you'll be giving each instance of the class 
meaningful values for those properties. 


There is one property of the class that could impair its 
usability. It will not reduce the developer’s productivity if 
each instance of the fldBoundDataField must have its 
DataSource or Datatype property. This is because the 
developer must probably set these properties even if he or 
she was using the standard data field object. However, 
remember that each instance of the class is also its own 
container, and this means that each instance of the class 
will have its own RecordSource property. 


Does a developer have to set the RecordSource property 
for each instance of the class, instead of just using the 
RecordSource property of the form that contains the class? 
This would seem to increase, rather than decrease, the 


developer’s work load. Setting an extra property for each 
instance of the class — as well as modifying the property 
if the RecordSource for the parent form changes — may 
actually reduce a developer’s productivity. Fortunately, this 
problem has an easy solution. 


Shared Recordsets and Relative References 

OPO uses a recordset to hold data returned from a data- 
base. A recordset is associated with a container object 
through the object’s RecordSource property. This is the 
name of a table or a view in the database that has been 
opened in the associated session. 


Normally, you would designate an individual recordset for 
each container in your application. For instance, you 
might have one recordset to hold the master data and 
another recordset for the associated detail data, with a dif- 
ferent container object for each source table for the data. 
Occasionally, you'll want to use the same set of data for 
more than one container. To show some of the data for a 
particular record in your main form, and also allow the 
user to display a dialog box with additional information 
about a record (see Figure 2), you would want to share the 
same recordset between the main form and the dialog box. 
You can share a recordset between more than one recordset 










Order ID: ja Order Date: | 7/17/95 


o_o 
[=| Address fy [4] 


Address: |100 Twin Dolphin Drive 
Redwood Shores 94065 
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2" Scented Candle, B 







10" Beeswax Taper, S 


Figure 2: The main form and dialog box that share a recordset. 


by using the equal sign ( = ) as the first character in the 
containers RecordSource property. Let’s say the main form 
in our example is named frmMain. The RecordSource 


property for the dialog box would be: 
=frmMain 


You can combine the ability to share recordsets with the capa- 
bility to define relative references in OPO. Some of OPO’s 
functionality comes from its container objects, such as forms, 
repeaters, and instances of classes. You can always access a 
container object by its name, and you can also reference a 
container by its position in reference to the current object. 
The keyword container is a relative reference that specifies the 
current object's container. 


The instances of the clsBoundDataField class will be 
their own containers, but they will typically want to share 
the recordset with their parent form or repeater. 
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Step 4: Set the RecordSource of the clsBoundDataField 
class to: 


=container 


By default, the instances of your class will share the 
recordset of their parent container. The container keyword 
sets the RecordSource of the class instance to the same 
RecordSource as the parent container. If you should 
change the RecordSource of the parent form or repeater, 
you dont have to change anything in the instances of the 
clsBoundDataField class. 


Finishing the Class 

To complete our class, we have to add a little code to dis- 
play a message box that describes the bound data column 
for an instance of our class. While in an instance of our 
class, the user can then display the message box at any 


time by pressing [(F2 ]. 


Add the following code to the OnKey method of the 
f1dBoundDataField in the clsBoundDataField class: 


IF keycode = KEYCODE F2 THEN 
IF NOT ISNULL(Self.DataSource) THEN 
MSGBOX( "This field is bound to the " & 
Self.DataSource & & 
"column.", 64, "Bound Data Field") 
ELSE 
MSGBOX("This field is not bound to a data column.", & 
32, "Unbound Data Field") 
END IF 
END IF 


This will display a message box with either the name of 
the column that is bound to the data field, or a message 
box indicating that the field is not bound to any particular 
column. As you can see, the code uses the keycode con- 
stant, KEYCODE_F2, which is passed to the OnKey 
method to determine if was pressed. 


Step 5: Now, we have to create a form that will use 
instances of our class. This is done so that we can test the 
class’ functionality: 

m Create an application by clicking on the New 
Application button in the tool bar or selecting File | 
New Application. Now create a new form for the appli- 
cation by either clicking on the New Form button or 
choosing File | New Form. 

m Set the form’s RecordSrcSession property to MLDATA, 
the default session that comes with OPO. Set the 
form’s RecordSource property to EMP. 

m Add a horizontal scroll bar to the form. 

m Add three instances of the clsBoundDataField class 
to the form by dragging the class icon into the form. 
You must have the library window and the form win- 
dow available in your workspace to accomplish this. 


Notice that whenever you add an instance of a class to a 
form, the instance appears, by default, in the upper left 
corner of the form, regardless of where it’s dropped. 


Step 6: Set the DataSource property of the first 
f1dBoundDataField object to ENAME and the Datatype 
property to String. Set the DataSource property of the sec- 
ond fldBoundDataField object to JOB and its Datatype 
property to String. Set the DataSource property of the 
third fldBoundDataField object to MGR and the Datatype 
property to String. Add static text labels to clarify the form. 


We're ready to test our form. Run the form and move the 
cursor into the first instances of the clsBoundDataField. 
Press (F2]. Your application should resemble Figure 3. 






7369 







Employee ID: 


Employee Name: 











= Bound Data Field 


@ This field is bound to the ENAME column. 


Job: 
Manager: 


Hire Date: 


Figure 3: The test application with the informative message box. 


Our class was quite easy to develop, and we can use it to 
implement this useful functionality throughout our 
entire application. We can also move the class into a 
library so that it can be used in many different applica- 
tions. This is the reason we created a class with this func- 
tionality, instead of placing the code in the parent form’s 


OnChildKey method. 


Adding similar code to the OnChildKey method of the 
form would work for one form, but must be repeated in 
every form requiring the same functionality. This not only 
adds more work, but also makes it more difficult to apply 
any changes that would be required in the functionality — 
we would have to make sure to apply the same changes to 
each implementation of the code. 


Creating a class that can be widely used has given us a nice 
increase in productivity. We can do even more by creating 
another class that will use the functionality of this class and 
add more specific functionality to handle required fields. 


Required Fields 

Every application I have ever worked on has included 
some required fields. A required field must contain a value 
when the data is stored in the database. 


We must ensure that required fields contain a value, or the 
database will return a run-time error. You can always force 
a value for required fields by using radio buttons or check 
boxes to assign a value to the field, since both of these 
objects can be configured to always have a value. 
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Required fields present a different sort of problem when 
they are represented by data fields. It would be very help- 
ful if we could create a class that could be easily used to 
ensure that all required fields contain data before the data 
is written. By using our new clsBoundDataField as the 
foundation for another class, we can create simple applica- 
tion logic to handle any number of required fields. 


Creating a Subclass 

Now, we'll create a subclass based on the clsBoundDataField 
class to check for required fields. A subclass inherits all the 
properties and methods of the parent class. 


Step 7: Select the clsBoundDataField class icon in the 
library window. Select Edit | Create Subclass from the 
menu. Set the Name property of the new class to 
clsRequiredField. 


Notice that the new class does not show any of the code of 
its parent class. Next, we'll create a user-defined property 
that will indicate whether an instance of our new class is a 


required field, and add it to the class. 


Step 8: Open the Property sheet for the clsRequiredField 
class. Open the User Properties dialog box by clicking on the 
button in the Property sheet’s toolbar. Add a user-defined 
property in the User Properties dialog box with a Name of 
udpRequired, a Type of Property and a Datatype of 
Boolean. Add the property to the clsRequiredField class 
by dragging the box on the left of the User Properties sheet to 
the Property sheet for the clsRequiredField (see Figure 4). 
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Figure 4: Adding the udpRequired user-defined property to 
the clsRequiredField class. 


Step 9: Set the value of the udpRequired property to True. 


Why did we use a property to determine if an instance of the 
clsRequiredField class is actually required? There are two 
reasons for this. First, we must be able to identify an instance 
of the class by the presence or absence of the property (we'll 
discuss this a little later). The other reason is to make the class 
even more flexible. Although most required fields are always 
“required,” there may be some situations in your applications 
when a field is required, and not required in others. By allow- 
ing the udpRequired property to determine if a particular 


instance of the class is required at any time, you can handle 
this variable situation with the same class. 


We're ready to add a couple of instances of our new 
class to our sample application, and to implement logic 
that will let us use the class to check for null values in 


the required fields. 


Step 10. Drag two instances of the clsRequiredField 
class into the sample application you created earlier. Set 
the DataSource property for the first instance of the 
f1dBoundDataField to EMPNO and the Name property to 
f1dEmployeeNumber. Set the DataSource for the second 
instance of the fldBoundDataField to HIRE_DATE, the 
Name property to fldHireDate, the Datatype property 
to Date, and the FormatMask property to Short Date. 


Checking for Required Fields 

We can now use the instances of the clsRequiredField 
class to ensure that they contain data before committing 
any changes in the data on screen. The CommitWork 
method for the form is triggered before any data is writ- 
ten to the database, so this is where we should add code 
to check for values. We must add code to this method 

to walk through the objects in the form, check if they 
are required fields, and prevent writing to the database if 
any of the required fields do not contain a value. 


We'll accomplish this with some Oracle Basic functions 
and the HasProperty operator, new in version 1.0.16 of 


OPO. The HasProperty operator uses the form: 
object HasProperty property 


The comparison returns a Boolean value that is True if the 
object has the property, and False otherwise. 


Step 11: Add a pushbutton to your form. Set its Name 
property to pbCommitChanges and the Label property to 
Commit Changes. 


Step 12. Add the code in Figure 5 to the pushbutton’s 
Click method. 


DIM objChild As Object 
objChild = container.FirstChild 
DO WHILE NOT ISNULL(objChild) 
IF objChild HasProperty udpRequired THEN 
IF ISNULL(objChild.FirstChild.Value) THEN EXIT DO 
END IF 
objChild = 
LOOP 
IF NOT ISNULL(objChild) THEN 
MSGBOX( "You must enter a value for the " & & 
objChild.FirstChild.Name & ".", 16, & 
"Value Required" ) 
objChild.FirstChild.SetFocus() 
ELSE 
container .CommitWork () 
END IF 


objChild.NextControl 


Figure 5: Setting the value of objChild to the form’s first object. 
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The code in Figure 5 sets the value of the objChild vari- 
able to the first object in the form and uses the DO loop 
with the NextControl function to walk through all the 
objects in the form. The HasProperty operator is used to 
identify instances of the clsRequiredField class. 


If an object is an instance of the clsRequiredField 
class, the code checks to ensure that the FirstChild 
object in the class is not null. The relative FirstChild 
reference will always take us to the data field since it’s the 
only object in the class. In addition, the relative reference 
allows us to give a more descriptive name to the field, 
since the Name property will be used in the message box 


that appears if the field is null. 


If the field is null, the DO loop is exited. Then, the IF 
clause checks if the ob jChild variable is null. If so, the 
loop completed successfully, which means that all the 
required fields contain data and the changes can be 
committed to the database. If the variable is not null, it 
means the EXIT DO statement ended the loop when a 
required field did not contain a value, and the variable 
will contain the object handle of the errant field. The 
code displays a message box to explain the problem to 
the user and places the focus into the transgressing field. 


Note that the code will immediately exit the DO loop 
when one required field is found to be null. You don't 
really care how many required fields are null. If any of 
them are null, you must prevent the data from being 
written to the database. Once you find one required 
field that is null, there is no need to check any of the 
others since the data in the form already violates data 
integrity rules. If you did not immediately exit the DO 
loop and had more than one required field that did not 
contain a value, your users would see a confusing suc- 
cession of flashing message boxes. 


Step 13: To see how 
this all works togeth- 
er, let’s run the form. 
Delete the value from 
the data field that is 
bound to the EAPNO 
column. Click on the 
Commit button in 
the tool bar. Your 
application should 
look like the form in 
Figure 6. 


= Required Data 


@ The fldEmployeeNumber must have a value 


Hire Date: | 12/17/80 
Commit Changes 


Figure 6: The errant form. 





The clsRequiredField class can be used in any form, for 
any number of required fields. You can add or delete 
required fields from a form without worrying about 
changing the above code. 


Conclusion 

You can use the classes we created in all of your applica- 
tions. You could include a version of the above code in 
another object class that you could add to your form. This 
would make implementing the functionality even easier. 


Next month, we'll take a sneak peak at some of the features 


of the 2.0 release of Oracle Power Objects. Cll 


The demonstration applications and objects referenced in this 
article are available on the Oracle Informant Works CD 
located in INFORM\96\MAY\ OL9605RG. 
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